docs(repo): codify StyleX best practices in the Mosaic skill by alexcarpenter · Pull Request #9238 · clerk/javascript

alexcarpenter · 2026-07-24T12:42:41Z

Summary

Expands .claude/skills/mosaic/references/stylex.md into an evidence-backed do/don't StyleX authoring guide, from a full sweep of the astryx design system (~120 components).

New/rewritten sections:

Breaking up stylex.create — base object + prop-keyed variant maps + small state objects, composed in one stylex.props(...); don't monolith, don't per-property, don't inline-ternary a variant (that's a missing map).
Dynamic styles: dos and don'ts — dynamic functions are for continuous/derived runtime values only (not closed enums). Key sub-distinction: write a --var and let a static rule consume it (one atom, survives consumer @media overrides, inherits to descendants) vs. set the property raw (per-instance only).
Scoped ancestor states — stylex.when.ancestor() + defineMarker() in place of parent-selector hacks.
Tightened tokens, conditions/state, and composition guidance throughout.

Corrections / decisions

Marker files are <comp>.markers.stylex.ts (a .stylex.ts define-primitive file), not .markers.ts — verified against the @stylexjs/eslint-plugin enforce-extension rule source.
File-layout section now separates rule-forced facts (.stylex.ts = define* only; create may not live there) from Mosaic house convention: stylex.create lives in a co-located <comp>.styles.ts, never inline in the .tsx. This is a deliberate divergence from astryx (which inlines), recorded as our choice rather than a research finding.

Verification

Key claims spot-checked against astryx source: when.ancestor/defineMarker (real), dynamic functions (47 uses), firstThatWorks/attrs (0 uses), the CodeBlock/AvatarGroup var-writing pattern, and the enforce-extension behavior.

Changeset

Empty — repo/tooling-only doc change, no user-facing package impact.

Expand references/stylex.md into an evidence-backed do/don't guide from a sweep of the astryx design system: sections on breaking up stylex.create (base + variant maps + state objects) and dynamic styles (write-a-var vs set-property, perf model). Fix marker files to .markers.stylex.ts, add scoped ancestor states, and record the Mosaic convention that stylex.create lives in a co-located .styles.ts, never inline in the .tsx.

changeset-bot · 2026-07-24T12:42:46Z

🦋 Changeset detected

Latest commit: 00df215

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-07-24T12:42:47Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 24, 2026 12:49pm
swingset	Ready	Preview, Comment	Jul 24, 2026 12:49pm

…ner focus rings

coderabbitai · 2026-07-24T12:48:28Z

📝 Walkthrough

Walkthrough

Added a changeset for the Mosaic StyleX best-practices documentation. Expanded the StyleX reference with file-layout rules, token conventions, static-analysis requirements, composition patterns, conditional states, scoped ancestor markers, dynamic-style guidance, prop precedence, and CSS feature caveats.

Estimated code review effort: 3 (Moderate) | ~25 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the documentation-focused StyleX guidance added to the Mosaic skill.
Description check	✅ Passed	The description matches the doc-only StyleX guide expansion and its main topics.

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.claude/skills/mosaic/references/stylex.md:
- Around line 252-253: Fix the malformed inline code spans in the style
examples: keep the full tree-row indentation expression and line-clamp
expression, including their internal spaces, within a single code span so the
Markdown passes MD038. Leave the staggered animationDelay example unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 2eea5fd0-0e18-44ec-86d8-385453c431e5

📥 Commits

Reviewing files that changed from the base of the PR and between 1f8d89f and 5dd6ce0.

📒 Files selected for processing (2)

.changeset/mosaic-stylex-best-practices.md
.claude/skills/mosaic/references/stylex.md

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

clerk/clerk_go (manual)
clerk/dashboard (manual)
clerk/accounts (manual)
clerk/backoffice (manual)
clerk/clerk (manual)
clerk/clerk-docs (manual)
clerk/cloudflare-workers (manual)
clerk/cli (auto-detected)
clerk/clerk-ios (auto-detected)
clerk/clerk-android (auto-detected)

coderabbitai · 2026-07-24T12:48:31Z

+tree-row indent `(depth-1) \* step`, a line clamp `n => ({ WebkitLineClamp: n })`,
+a staggered `animationDelay`.


📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Fix the malformed inline code spans.

The indentation and line-clamp examples contain spaces inside code spans and trigger MD038. Keep the entire expression inside one code span.

Proposed fix

- tree-row indent `(depth-1) \* step`, a line clamp `n => ({ WebkitLineClamp: n })`, + tree-row indent `(depth - 1) * step`, a line clamp `n => ({ WebkitLineClamp: n })`,

🧰 Tools

🪛 markdownlint-cli2 (0.23.0)

[warning] 252-252: Spaces inside code span elements

(MD038, no-space-in-code)

[warning] 252-252: Spaces inside code span elements

(MD038, no-space-in-code)

[warning] 253-253: Spaces inside code span elements

(MD038, no-space-in-code)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.claude/skills/mosaic/references/stylex.md around lines 252 - 253, Fix the malformed inline code spans in the style examples: keep the full tree-row indentation expression and line-clamp expression, including their internal spaces, within a single code span so the Markdown passes MD038. Leave the staggered animationDelay example unchanged.

Source: Linters/SAST tools

pkg-pr-new · 2026-07-24T13:27:07Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9238

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9238

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9238

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9238

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9238

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9238

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9238

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9238

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9238

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9238

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9238

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9238

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9238

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9238

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9238

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9238

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9238

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9238

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9238

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9238

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9238

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9238

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9238

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9238

commit: 00df215

kylemac

stamp made of rubbah

vercel Bot deployed to Preview – clerk-js-sandbox July 24, 2026 12:43 View deployment

vercel Bot deployed to Preview – swingset July 24, 2026 12:44 View deployment

alexcarpenter added 2 commits July 24, 2026 08:46

docs(repo): prefer :has(:focus-visible) over :focus-within for contai…

c968909

…ner focus rings

docs(repo): update Mosaic StyleX doc to mergeStyleProps rename

00df215

vercel Bot deployed to Preview – clerk-js-sandbox July 24, 2026 12:47 View deployment

coderabbitai Bot reviewed Jul 24, 2026

View reviewed changes

vercel Bot deployed to Preview – swingset July 24, 2026 12:49 View deployment

coderabbitai Bot mentioned this pull request Jul 24, 2026

feat(ui): add Mosaic Popover component #9241

Open

5 tasks

kylemac approved these changes Jul 24, 2026

View reviewed changes

alexcarpenter merged commit e657593 into main Jul 24, 2026
48 of 49 checks passed

alexcarpenter deleted the carp/mosaic-stylex-skill branch July 24, 2026 14:29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(repo): codify StyleX best practices in the Mosaic skill#9238

docs(repo): codify StyleX best practices in the Mosaic skill#9238
alexcarpenter merged 3 commits into
mainfrom
carp/mosaic-stylex-skill

alexcarpenter commented Jul 24, 2026

Uh oh!

changeset-bot Bot commented Jul 24, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 24, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 24, 2026 •

edited

Loading

Walkthrough

Uh oh!

coderabbitai Bot left a comment

Uh oh!

coderabbitai Bot Jul 24, 2026

Uh oh!

pkg-pr-new Bot commented Jul 24, 2026

Uh oh!

kylemac left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		tree-row indent `(depth-1) \* step`, a line clamp `n => ({ WebkitLineClamp: n })`,
		a staggered `animationDelay`.

Uh oh!

Conversation

alexcarpenter commented Jul 24, 2026

Summary

Corrections / decisions

Verification

Changeset

Uh oh!

changeset-bot Bot commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

pkg-pr-new Bot commented Jul 24, 2026

Uh oh!

kylemac left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot Bot commented Jul 24, 2026 •

edited

Loading

vercel Bot commented Jul 24, 2026 •

edited

Loading

coderabbitai Bot commented Jul 24, 2026 •

edited

Loading